home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 November / EnigmA AMIGA RUN 02 (1995)(G.R. Edizioni)(IT)[!][issue 1995-11][Skylink CD].iso / earcd / util / misc / tlist008.lha / tl.doc < prev   
Text File  |  1995-08-08  |  14KB  |  434 lines
  1.                      TurboList v0.08 alpha (8-Aug-95)
  2.                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4.                          coded by Conrad Sanderson
  5.                     (e-mail: g.sanderson@ais.gu.edu.au)
  6.  
  7.                 Mail me with bug reports or suggestions...
  8.  
  9. NOTE:
  10.  
  11. I  gotta  finish  a  BEng  degree (and i'm aiming for Honors), hence i
  12. cannot  waste  time coding this thing.  I will only develop this thing
  13. further  when i get sick of studying or something.  With the way Escum
  14. is  proceeding  with the "development" of new Amigas, i'll be buying a
  15. PCI PowerMac as soon as i accumulate enough money.
  16.  
  17. I invite other Amiga coders (demos makers and utility writers) to join
  18. me  -  there's much work to be done in Amigaizing PCI PowerMacs, which
  19. have  some lovely hardware, but a semi-crap OS.  The philosophy behind
  20. my  move  is  long  -  but it's sufficient to say that the numbers (of
  21. various kinds) for Amiga don't add up anymore.
  22.  
  23.  
  24. TABLE OF CONTENTS
  25. ~~~~~~~~~~~~~~~~~
  26. 0.    Legal Notice
  27. 1.    Requirements
  28. 2.    Quick Overview
  29. 3.    List of features
  30. 4.    Why is it faster?
  31. 5.    It's still experimental
  32. 6.    Options
  33. 7.    Aliasing
  34. 8.    History
  35. 9.    To do
  36.  
  37.  
  38. 0. LEGAL NOTICE
  39. ~~~~~~~~~~~~~~~
  40. TurboList is (c) Copyright 1995 Conrad Sanderson.
  41.  
  42. This program (TurboList) and its documentation files can be
  43. distributed and used freely, as long as all of the following
  44. conditions are satisfied:
  45.  
  46.     0.1 the executable and documentation file(s) are not
  47.         modified in any way.
  48.  
  49.     0.2 the executable and documentation file(s) are
  50.         not stored on, or transferred from,
  51.         (in any manner) any device which is property
  52.             (whole or partially) of Microsoft or any of
  53.         its subsidiaries (owned whole or partially by
  54.         Microsoft).
  55.  
  56.     0.3 any breaches of conditions 0.1 and 0.2 must be reported
  57.         to me (Conrad Sanderson) immediately.
  58.  
  59. Failure  to obey the above conditions (0.1, 0.2 and 0.3) is treated as
  60. a  violation  of copyright laws AND acceptance of all of the following
  61. conditions:
  62.  
  63.     0.4 each copy of the executable and documentation file(s)
  64.         requires a license for either use, distribution or storage.
  65.  
  66.     0.5 Each license can be obtained from me (Conrad Sanderson)
  67.         for US$1,000,000.00
  68.  
  69.  
  70. 1. Requirements
  71. ~~~~~~~~~~~~~~~
  72. At least Kickstart 2.04 (v37.175)
  73.  
  74. The  68020  version  requires  at  least a 68020 processor (ie.  Amiga
  75. A1200,  CD32,  A2500,  A3000,  A4000  or  any  machine  with  a 68020+
  76. accelerator).  This version has been specifically optimized for 32 bit
  77. memory  access  and  32  bit  maths and hence is faster than the 68000
  78. version.
  79.  
  80. The  68000  version  can  be used on any Amiga, but is best suited for
  81. machines which only have the 68000 or the 68010 processor (A500, A600,
  82. A2000).
  83.  
  84. The  are 2 executables supplied in the archive:  "tl.020" and "tl.000"
  85. rename the appropriate one for your computer to "tl".
  86.  
  87.  
  88. 2. Quick Overview
  89. ~~~~~~~~~~~~~~~~~
  90. NEW:  as of v0.08, TurboList is pure and hence can be made resident.
  91. If the 'p' bit (indicating pure) is not set when the executable is
  92. extracted from the archive, use
  93.  
  94. shell>  protect tl +p
  95.  
  96. Once the 'p' bit is set, use
  97.  
  98. shell> resident tl
  99.  
  100. to  make  it  resident (can be part of startup).  This way tl will not
  101. have to be loaded from disk each time it's used.
  102.  
  103.  
  104. TurboList  is  a command similar to the standard list command supplied
  105. with AmigaDOS.
  106.  
  107. The normal 'list' command, lists files like this:
  108.  
  109. etherpeek                   2369 ---arwed 04-Jan-95 22:21:34
  110. alien.iff                1314114 ----rwed 07-Jan-95 01:31:08
  111. desert.rat.toxic.article.gz    3684 ----rwed 05-Apr-95 17:24:34
  112. ultoa020.o                   444 ----rwed 28-Mar-95 19:11:11
  113. ftphunt.gz                 13768 ---arwed 04-Jan-95 14:27:41
  114. mui23usr.LZX              504572 ----rwed 26-Mar-95 19:21:54
  115. electric.bullet             1416 ---arwed 04-Jan-95 22:16:54
  116. ar311.lha                  95557 ----rwed Today     02:44:23
  117. replacement.functions       1029 ----rwed 11-Mar-93 23:20:17
  118. 9 files - 3796 blocks used
  119.  
  120.  
  121. TurboList lists them like this (similar to unix ls):
  122.  
  123. ---arwed 04 Jan 22:21   2.3 K  etherpeek
  124. ----rwed 07 Jan 01:31   1.3 M  alien.iff
  125. ----rwed 05 Apr 17:24   3.6 K  desert.rat.toxic.article.gz
  126. ----rwed 28 Mar 19:11   0.5 K  ultoa020.o
  127. ---arwed 04 Jan 14:27  13.4 K  ftphunt.gz
  128. ----rwed 26 Mar 19:21 492.8 K  mui23usr.LZX
  129. ---arwed 04 Jan 22:16   1.4 K  electric.bullet
  130. ----rwed Tod 02:44:23  93.3 K  ar311.lha
  131. ----rwed 11 Mar  xx93   1.0 K  replacement.functions
  132. TOTAL:  9 files [1.8 M] and 0 dirs [1.9 M used, 1.0 M free]
  133.  
  134.  
  135. As  you  can  see,  long  filenames  do  not  stuffup  the formatting.
  136. Additionally,  file sizes are approximated to their nearest multiplier
  137. (ie.   Kilobytes,  Megabytes  or  Gigabytes),  which is much easier to
  138. read.  This behaviour can be switched off.
  139.  
  140. The  date/time  output  is also different - if the file was created on
  141. the  day  you  are listing it, it will print out "Tod hh:mm:ss", where
  142. Tod  = Today, hh = hours, mm = minutes, ss = seconds.  If the file was
  143. created  within  6 months of Today, the day of the month and the month
  144. will  be  printed,  along  with  hh:mm.   If  the file is older than 6
  145. months,  the  full  date,  but  no  time,  is printed.  This unix-like
  146. behaviour  can  be  switched off and the full date printed without any
  147. conditions.
  148.  
  149. Additionally,  the  file sizes are added up and listed at the end (the
  150. [1.8  M]  in  above example).  The actual space taken up by the listed
  151. files is also printed (ie.  1.9 M used) - this is due to the amount of
  152. blocks  being used for a file, and blocks have constant sizes (usually
  153. 512  bytes  on  FFS),  hence  a file which takes up 444 bytes actually
  154. takes up 2 blocks, 1 * 512 for the file, and 1 * 512 for the directory
  155. entry  (these  values all depend on the file system used).  The amount
  156. of free space (ie.  1 M free) on the device is also printed.
  157.  
  158. Files  which  have  the  hidden  ('h')  protection bit enabled will be
  159. ignored and not taken into account when counting sizes/space taken up.
  160. This can be switched off.
  161.  
  162. NOTE:   I have been informed that 'h' actually means hold, not hidden.
  163. However,  the  'h'  has  never been properly implemented in the OS and
  164. hasn't  been  documented  either.   I  will remove 'h' bit code (which
  165. detects  hidden  files)  from tl and replace it with looking for files
  166. which start with '.' (ie.  a dot).
  167.  
  168.  
  169. File size conversion explanation:
  170.  
  171. K = 1024 bytes    (1 Kilobyte)
  172. M = 1024 K    (1 Megabyte)
  173. G = 1024 M    (1 Gigabyte)
  174.  
  175. NOTE: If any of the above values exceed 4 Gigabytes, strange/incorrect
  176.       results will be printed... but not many people have 4 Gigabyte
  177.       drives.
  178.  
  179.  
  180. 3. List of features
  181. ~~~~~~~~~~~~~~~~~~~
  182.  - Can be upto 30% faster than the normal 'list' command
  183.  - Long filenames fit without stuffing up the display
  184.  - Approximates the file size so it can be read easily (can be turned off)
  185.  - similar to unix-ls date printing behaviour
  186.  - doesn't display hidden files (with the h bit) (can be turned off)
  187.  - handles patterns (ie. stuff like foobar.#? etc)
  188.  - listing according to dates (since/upto date limitations)
  189.  
  190.  
  191. 4. Why is it faster?
  192. ~~~~~~~~~~~~~~~~~~~~
  193.  - grabs 3 filenames before printing them (can be turned off)
  194.    (note: caching filenames may not be desirable when using pattern
  195.           matching on a slow drive... will be fixed later)
  196.  - Turns off the cursor while printing, but turns it back on as soon
  197.    as it has finished printing a set of names.  The cursor can be
  198.    configured to remain on at all times.
  199.  - Direct writes (can be forced to use normal printing methods)
  200.  
  201.  
  202. 5. It's still experimental
  203. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  204.  - don't expect everything working perfectly
  205.  - a lot of functions are missing when compared to the normal list
  206.    command  eg. recursive directories
  207.  
  208.  
  209. 6. Options
  210. ~~~~~~~~~~
  211. The letters after '/' specify the type of argument
  212.  
  213. /M = multiple strings    (keyword doesn't have to be present)
  214. /S = switch (ie. enable) (keyword has to be present)
  215. /K = keyword followed by a string
  216.  
  217. If   a   keyword   (or   its   shortcut)   has  the  same  name  as  a
  218. directory/filename  you  are trying to list, you must use DIR=filename
  219. to  avoid the conflict.  Alternatively, you can use UNIX like keywords
  220. (see the "-unix" option for more information).
  221.  
  222.           DIR/M,
  223. -h=-?=HELP    = ABOUT/S,
  224. -sh=SH        = SHOWHIDDEN/S,
  225. -co=CO        = CURSORON/S,
  226. -nj=NJ        = NOJUMP/S,
  227. -nd=ND        = NODIRECT/S,
  228. -unix/S,
  229. -files        = FILES/S,
  230. -dirs        = DIRS/S,
  231. -noda=NODA    = NODATES/S,
  232. -ex=EX        = EXACT/S,
  233. -free        = FREE/S,
  234. -since        = SINCE/K,
  235. -upto        = UPTO/K,
  236. -normd=NORMD    = NORMALDATE/S
  237. -com=COM    = COMMENT/S
  238. -nototal    = NOTOTAL/S
  239.  
  240.  
  241. DIR
  242.  
  243. Name  of  a  directory  or  a file or nothing (will list current dir).
  244. Currently tlist can only process one name (no multiple directories).
  245.  
  246.  
  247. ABOUT, HELP, -?, -h
  248.  
  249. Print version/date information.  In some versions this option may also
  250. display various debugging information.
  251.  
  252.  
  253. SHOWHIDDEN, SH, -sh
  254.  
  255. Show hidden files/directories (h protection bit).
  256.  
  257.  
  258. CURSORON, CO, -co
  259.  
  260. Keep  the  cursor  on  at all times.  Tlist turns the cursor off while
  261. printing  something.   If  you  are  using tlist over a comm link (eg.
  262. modem  link, AUX:, null-modem, etc.), your terminal may not be able to
  263. interpret cursor on/off commands, hence this option.
  264.  
  265.  
  266. NOJUMP, NJ, -nj
  267.  
  268. Do  not  cache filenames - print out filnames as soon as they are read
  269. from  the  disk.   This  can  be used if you have a slow drive and are
  270. listing patterns.  Normally tlist caches 3 names before printing them.
  271. I'll  probably  change  the  name  of  this option to NOCACHE in later
  272. versions.
  273.  
  274.  
  275. NODIRECT, ND, -nd
  276.  
  277. Use  normal  printing methods instead of direct writes.  Direct writes
  278. may conflict with some console-handlers (eg.  KingCON with Jump Scroll
  279. enabled) or communication links.
  280.  
  281.  
  282. -unix
  283.  
  284. Instructs  tlist  to  use options _only_ which start with '-'.  Useful
  285. when a option has the same name as a dir/file, or you prefer UNIX type
  286. keywords.   Only  works  properly  when it is specified as part of the
  287. command line.
  288.  
  289. (note:    even if you do not specify -unix, options starting with '-'
  290.     still work. )
  291.  
  292.  
  293. FILES, -files
  294.  
  295. List only files
  296.  
  297.  
  298. DIRS, -dirs
  299.  
  300. List only directories
  301.  
  302.  
  303. NODATES, NODA, -noda
  304.  
  305. Do not print date/time of files/dirs.
  306.  
  307.  
  308. EXACT, EX, -ex
  309.  
  310. Print out the exact size of files (ie. no approximations).
  311.  
  312.  
  313. FREE, -free
  314.  
  315. Display the amount of used and free space only.  Example:
  316.  
  317. shell> tlist free dh0:
  318. [7.1 M used, 917.1 K free]
  319.  
  320. 'dh0:'  can  be  replaced  with  any filename/directory/device or even
  321. omitted.  If it's omitted, tlist will use the current directory as the
  322. argument.
  323.  
  324.  
  325. SINCE, -since
  326.  
  327. Limit  listing  of  files  to  only  those  which were created since a
  328. specified  date/time.   The  date/time  must  be specified in standard
  329. AmigaDOS format.  Examples of valid dates:  today, yesterday, thursday
  330. (ie.  any day of the week), 01-Jun-93, 2:08 (ie.  hh:mm), 2:08:01 (ie.
  331. hh:mm:ss).   When  specifying  a  time,  it  will  be  assumed you are
  332. referring to a time which was Today.
  333.  
  334.  
  335. UPTO, -upto
  336.  
  337. Similar to SINCE, but instead it limits listing of files to only those
  338. which were created upto a specified date/time.
  339.  
  340.  
  341. COMMENT, COM, -com
  342.  
  343. Display filecomments
  344.  
  345.  
  346. NOTOTAL, -nototal
  347.  
  348. don't print the TOTAL: ... 
  349.  
  350.  
  351.  
  352. 7. Aliasing
  353. ~~~~~~~~~~~
  354. You  can  alias  tlist to have a default behaviour which you want.  It
  355. has  to  be  aliased  for  every shell window you open (can be part of
  356. s:shell-startup)
  357.  
  358. Example1:
  359. shell> alias tlist tlist showhidden exact
  360.  
  361. ... and whenever tlist is used, the showhidden and exact options
  362. will be on.
  363.  
  364. Example2:
  365. shell> alias tlist tlist -unix
  366.  
  367. ... and whenever tlist is used, only options which start with '-'
  368. will be used.
  369.  
  370. In  later  versions  tlist  may also use environment variables, so the
  371. default behaviour can be modified globally.
  372.  
  373.  
  374. 8. History
  375. ~~~~~~~~~~
  376. 0.08    seperated fields by 2 spaces
  377.     seperated size multiplier by 1 space
  378.     modified date output to be more unix like
  379.     modified file size approximator to always display in x.x format
  380.     added COMMENT/S
  381.     added NOTOTAL/S
  382.     removed BOTH/S
  383.     can now be made resident: uses cres.o for resident startup,
  384.     hence the executable is larger than necessary.  Next version
  385.     may have a stripped down version of cres.o
  386.  
  387. 0.07    reversed order of fields when printing - now looks similar
  388.     to unix ls
  389.     modified code to use jump tables instead of checking variables
  390.     all the time when deciding what function to use.
  391.     modified filestats() - ignores hidden files completely
  392.     modified date output to look like unix ls
  393.     modified string handling function again... in time critical
  394.     code, replaced mystrcat() with combinations of mystrputchar(),
  395.     mystrputword(), mystrputlong() - results in smaller and faster
  396.     code
  397.     using memcpy() instread of mystrcat() when handling long strings
  398.     results in much less access to memory, hence faster
  399.     added SINCE, UPTO, NORMALDATE, and BOTH keywords
  400.     modified ultoa() so it can pad generated strings with spaces,
  401.     depending on the length of the generated string.  This made
  402.     mysprintf() totally redundant.
  403.  
  404. 0.06    major code update (read: optimized the crap out of it)
  405.     - replaced many occurances of strcat()/strcpy() with
  406.       mystrcpy()/mystrcat() which are much faster...  tlist
  407.       now accesses memory much less
  408.     - replaced most occurances of mysprintf() (and hence RawDoFmt())
  409.       with mystrcat()/mystrcpy()/mystrputchar()/ultoa()
  410.     - due to above changes, tlist now is ~8% faster than last version
  411.     added FREE keyword
  412.     rearranged filestats(), added total size of files and total space
  413.     used by files
  414.     added CPU check for 68020+ version
  415.     68000 version uses utility.library for 32 bit maths
  416.  
  417. 0.05    implemented patterns (#?.sfsf#? etc)
  418. 0.04    added dates
  419. 0.03    replaced many occurences of mysprintf() with strcat()/strcpy()
  420.     added filestats()
  421. 0.02    added protection bits
  422. 0.01    tested the theory that print buffering and no cursor would
  423.     speed up directory listing
  424.  
  425. 9. To do
  426. ~~~~~~~~
  427.     - show/don't show .info files (hidden by default, SHOWINFO)
  428.     - show files/dirs bigger/smaller according to specified size
  429.     - multiple directories
  430.     - recursive directories
  431.     - resolve the 'h' protection bit -> ie. hidden or take it out?
  432.     - make files starting with . hidden
  433.     - strip cres.o to bare essentials
  434.